Msgkart Collections API Integration

The Msgkart Collections API Integration enables automated ingestion of loan cases, real-time status updates (payments, DND, promise-to-pay, recalls), and SFTP-based reporting delivery.

Overview

• Specification Version: 1.0
• Base URL: https://alb-backend.msgkart.com/api/v1/collections
• Authentication Header: X-API-Key: {{api_key}}

---

01. Case Upload API

Uploads the loan cases to be worked on during the current cycle.

Endpoint

POST /api/v1/collections/cases

Request Headers

X-API-Key: {{api_key}}
Content-Type: application/json

Request Body

{
  "type": "case_upload",
  "status": "ready",
  "file": "https://your-bucket.s3.ap-south-1.amazonaws.com/allocations/2026-08-20-01.json?X-Amz-Signature=..."
}

Response

200 OK

File Structure Behind the URL

The file hosted at the provided URL must contain a root JSON object with a cases array:

{
  "cases": [
    {
      "caseId": "LN-99120045",
      "customer": {
        "customerId": "CU-77401",
        "fullName": "A. Customer",
        "primaryPhone": "+919999999999",
        "alternatePhones": ["+919876500000"],
        "language": "ta",
        "city": "Coimbatore",
        "state": "TAMIL NADU"
      },
      "productType": "PERSONAL_LOAN",
      "productName": "EasyCash 12M",
      "currency": "INR",
      "dpd": 22,
      "bucket": "0-30",
      "totalOutstanding": 16640.00,
      "totalOverdue": 8309.00,
      "minimumPayable": 2077.00,
      "nextDueDate": "2026-09-01",
      "lastPaidAt": "2026-07-11T19:06:46+05:30",
      "lastPaidAmount": 2077.00,
      "mandateStatus": "BOUNCED",
      "paymentUrl": "https://pay.example.com/a/PATNKG",
      "installmentsOverdue": [
        {
          "number": 4,
          "dueDate": "2026-06-17",
          "amount": 2077.00,
          "principal": 1851.00,
          "interest": 226.00,
          "penalty": 0
        }
      ],
      "priority": "HIGH",
      "updatedAt": "2026-08-20T09:12:44+05:30"
    }
  ]
}

---

02. Case Update API

Processes live changes to uploaded cases to prevent contacting customers who have already paid, opted out, or provided a promise to pay.

Endpoint

POST /api/v1/collections/cases/updates

Request Headers

X-API-Key: {{api_key}}
Content-Type: application/json

Supported Update Types

Update Type	Description	Status
PAID	A payment, part-payment, or reversal posts	Required
DND	Customer opts out, registers DND, or is placed off-limits	Required
PTP	A promise to pay is taken outside (branch, in-house team, another agency)	Required
RECALLED	Case is withdrawn from collection cycle	Required

Request Body

{
  "type": "update",
  "status": "ready",
  "file": "https://your-bucket.s3.ap-south-1.amazonaws.com/updates/2026-08-20-01.json?X-Amz-Signature=..."
}

Response

200 OK

File Structure Behind the URL

The file uses the same structure as the Case Upload payload, with one additional field per case: updateType. Only caseId and updateType are required; other fields are evaluated when present.

{
  "cases": [
    { "caseId": "LN-99120045", "updateType": "PAID" },
    { "caseId": "LN-99120088", "updateType": "DND" },
    { "caseId": "LN-99120091", "updateType": "PTP" }
  ]
}

---

03. SFTP Delivery

All raw records, metrics and recordings are pushed by Msgkart to your SFTP node.